feat(plugin): add graphql-limit-count plugin by AlinsRan · Pull Request #13372 · apache/apisix

AlinsRan · 2026-05-14T05:39:07Z

What does this PR do?

Add a new graphql-limit-count plugin that limits GraphQL request rates based on the depth of the query Abstract Syntax Tree (AST) within a given time window.

Why is this change needed?

Standard rate limiting counts every request equally, regardless of its computational cost. This is insufficient for GraphQL endpoints where the cost of execution scales with query complexity. A single deeply nested query can be far more expensive than dozens of simple ones:

# Shallow query: depth 1, cheap to execute
query { users }

# Deep query: depth 5, potentially expensive (N+1 queries, large result sets)
query { users { orders { items { product { category { name } } } } } }

Without depth-aware limiting, a client could exhaust server resources with a single request while staying well within a request-count limit.

The graphql-limit-count plugin solves this by using the GraphQL query AST depth as the cost for each request, powered by the existing limit-count infrastructure. This lets operators configure a single depth budget per time window and have it consumed proportionally by query complexity.

How does it work?

The plugin intercepts POST requests with application/json (containing a query field) or application/graphql content type.
It parses the request body to extract the GraphQL query string.
It calls graphql.parse() to build the AST and recursively counts the maximum selections nesting depth.
Fragment spreads (...FragName) and inline fragments (... on Type { ... }) are fully expanded before depth is computed, with cycle detection to prevent infinite loops.
It calls limit_count.rate_limit(conf, ctx, plugin_name, depth), passing the depth as the cost.
If the accumulated cost within the time window exceeds count, the request is rejected with the configured rejected_code.

Example

Configure a route to allow a cumulative query depth of 10 per minute per client IP:

curl http://127.0.0.1:9180/apisix/admin/routes -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "graphql-rate-limited",
    "uri": "/graphql",
    "plugins": {
      "graphql-limit-count": {
        "count": 10,
        "time_window": 60,
        "rejected_code": 429,
        "key": "remote_addr"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": { "127.0.0.1:1980": 1 }
    }
  }'

A depth-4 query consumes 4 out of 10. After the budget is exhausted:

curl -i http://127.0.0.1:9080/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query": "query { foo { bar { baz { id } } } }"}'

# HTTP/1.1 200 OK
# X-RateLimit-Limit: 10
# X-RateLimit-Remaining: 6

# (after quota exhaustion)
# HTTP/1.1 429 Too Many Requests

Fragment spreads are expanded before computing depth, so the following query has the same depth (5) as the equivalent inline query:

fragment DeepFields on User {
  orders { items { product { category { name } } } }
}
query { user { ...DeepFields } }

Chained fragments (A spreading B spreading C) are also handled correctly.

Changes

File	Change
`apisix/plugins/graphql-limit-count.lua`	New plugin (priority 1004) with AST depth calculation, fragment expansion, cycle detection, and configurable max body size
`t/plugin/graphql-limit-count.t`	26 test cases covering normal flow, fragment spreads, inline fragments, cycle detection, charset content-type, max body size, and Redis/Redis-cluster policies
`apisix/cli/config.lua`	Register plugin; add `plugin-graphql-limit-count` and `plugin-graphql-limit-count-reset-header` shared dict defaults
`apisix/cli/ngx_tpl.lua`	Conditional shared dict declarations for the plugin
`conf/config.yaml.example`	Register plugin and shared dicts
`docs/en/latest/plugins/graphql-limit-count.md`	English documentation with examples
`docs/zh/latest/plugins/graphql-limit-count.md`	Chinese documentation with examples
`docs/en/latest/config.json`	Add to Traffic sidebar
`docs/zh/latest/config.json`	Add to 流量控制 sidebar
`t/admin/plugins.t`	Register plugin in admin test list

Add a new plugin that limits GraphQL request rates based on query AST depth using a fixed window algorithm. The plugin reuses the limit-count infrastructure for counter management and supports local, Redis, and Redis cluster policies. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add Apache license header to t/plugin/graphql-limit-count.t - Add plugin and shared dict entries to conf/config.yaml.example - Rewrite EN/ZH docs to follow open-source format with Tabs and realistic curl examples showing expected response headers Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add canonical link in <head> section - Use correct attribute table format (Name/Type/Required/Default/Valid values/Description) - Replace Tabs component with plain curl examples - Follow the same structure as traffic-label and exit-transformer docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds a new graphql-limit-count traffic control plugin that reuses limit-count infrastructure to charge requests by parsed GraphQL query depth.

Changes:

Adds the new plugin implementation and registers it in default plugin/admin configuration.
Adds NGINX shared dict configuration for the plugin.
Adds tests, documentation, and sidebar entries for English and Chinese docs.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
`apisix/plugins/graphql-limit-count.lua`	Implements GraphQL parsing, depth calculation, and limit-count integration.
`apisix/cli/config.lua`	Adds plugin and shared dict defaults.
`apisix/cli/ngx_tpl.lua`	Adds conditional shared dict declarations.
`conf/config.yaml.example`	Registers plugin and shared dicts in example config.
`t/plugin/graphql-limit-count.t`	Adds plugin functional tests.
`t/admin/plugins.t`	Adds plugin to admin plugin list expectations.
`docs/en/latest/plugins/graphql-limit-count.md`	Adds English plugin documentation.
`docs/zh/latest/plugins/graphql-limit-count.md`	Adds Chinese plugin documentation.
`docs/en/latest/config.json`	Adds English sidebar entry.
`docs/zh/latest/config.json`	Adds Chinese sidebar entry.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- fix max_query_depth: use proper max nesting depth traversal instead of counting total selection set nodes - fix content-type matching: use has_prefix instead of exact equality to handle types with charset parameters (e.g. application/json; charset=utf-8) - remove incorrect 'query' keyword check for application/graphql requests: shorthand queries and mutations are valid without 'query' keyword - fix max_size: read graphql.max_size from local config instead of passing nil (no limit) to get_body - fix typo: cant't -> can't in error message - return specific error message from check_graphql_request instead of generic 'no query' - fix ngx_tpl.lua: declare plugin-limit-count-redis-cluster-slot-lock dict when graphql-limit-count is enabled without limit-count - fix tests: add no_shuffle(), redis flush in init_worker, rejection path test, application/graphql content-type success test, and update response_body assertions to match specific error messages

The shared dicts (plugin-graphql-limit-count, plugin-graphql-limit-count-reset-header, and plugin-limit-count-redis-cluster-slot-lock) are already generated by ngx_tpl.lua when graphql-limit-count is enabled. Declaring them again in http_config caused nginx to fail with 'already defined' error.

The test framework t/APISIX.pm maintains a hardcoded list of shared dicts for the test nginx environment. New plugin dicts must be added here, otherwise ngx.shared[dict] returns nil at request time. Add plugin-graphql-limit-count and plugin-graphql-limit-count-reset-header to the list, following the same pattern as plugin-ai-rate-limiting.

Separate test blocks cause nginx to restart between them, resetting the shared dict counter. Merge the two rate limit checks (200 + 503) into a single pipelined_requests block so both requests share the same nginx instance and counter state. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

membphis · 2026-05-22T07:16:57Z

node_depth currently walks the raw AST and takes the maximum selections nesting it sees, but it does not expand a FragmentSpread at the point where the fragment is used. This lets clients move deeply nested fields into a fragment and reference it from a shallow query, causing the calculated cost to be lower than the actual query depth.

Example:

query {
  user {
    ...Deep
  }
}

fragment Deep on User {
  posts {
    comments {
      author {
        id
      }
    }
  }
}

The plugin should first build a fragment definition map, then calculate depth from the operation selection set. When it encounters a FragmentSpread, it should expand it in place; when it encounters an InlineFragment, it should continue calculating from that selection set; and it should guard against fragment cycles. Please also add tests for depth accounting with fragment spreads and inline fragments.

…s in depth calculation Fragment spreads (named fragments) and inline fragments were not expanded during depth traversal, allowing clients to hide deeply-nested queries behind fragments and bypass the depth-based rate limit. Fix: - fragmentSpread nodes are expanded in place by recursing into the referenced fragment's selections (via a fragment map built from the document definitions). - inlineFragment nodes are treated as transparent wrappers, recursing directly into their selections without adding an extra depth level. - A visited set guards against fragment definition cycles to prevent infinite recursion. - Only executable operation definitions are traversed for depth; fragment definitions are excluded from the root traversal to avoid standalone depth being counted independently. Tests added for fragment spread depth, inline fragment depth, and fragment cycle protection. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…e tests - Fix fragment map key bug: def.name is a Name AST node {kind='name', value='...'}, not a plain string. Use def.name.value as map key and node.name.value for lookup. - Add TEST 11: verify application/json; charset=utf-8 is accepted - Add response_headers_like assertion to fragment cycle test Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Split TEST 20 into a setup block (TEST 20) and hit block (TEST 21) so the inline fragment depth assertion does not rely on accumulated counter state from the preceding fragment-spread test. Both tests now independently verify that depth-4 queries consume 4 quota units from a fresh count-20 window. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…mber The max_size config value is read via try_read_attr and may arrive as a string if the YAML value is quoted or sourced from an env substitution. Use tonumber() to ensure a numeric value is passed to get_body, falling back to the default when the config value is not a valid number. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…e limit Add TEST 23 (route setup with max_size: 100) and TEST 24 (oversized request body returns 400) to cover the graphql.max_size enforcement path. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…nimum 1 - Reject zero/negative graphql.max_size from config to avoid accepting no requests or behaving unexpectedly; fall back to default 1MiB. - Clamp computed depth to minimum 1 before rate limiting so that a degenerate operation with no selections never bypasses rate limiting with cost=0. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

lj-releng reports an error for Lua globals accessed without local bindings. Add local tonumber = tonumber with the other local aliases. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

… test Add response_body_like assertion to TEST 24 to confirm the 400 is specifically from the body size limit, not an unrelated validation error. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace raw body content in error logs with body size in bytes to prevent leaking sensitive user data (PII or secrets) from GraphQL request payloads into log files. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…_size The body size limit triggers core.log.error which conflicts with the default no_error_log [error] added by the preprocessor. Add error_log to expect the size-exceeded log and replace the default check. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add TEST 25/26 to verify that fragment spreads referencing other fragments (A->B) are fully expanded when computing query depth. This covers the scenario where a shallow root query uses a fragment that itself uses another fragment to reach deeply nested fields. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

dosubot Bot added size:XL This PR changes 500-999 lines, ignoring generated files. doc Documentation things enhancement New feature or request plugin labels May 14, 2026

dosubot Bot added size:XXL This PR changes 1000+ lines, ignoring generated files. and removed size:XL This PR changes 500-999 lines, ignoring generated files. labels May 14, 2026

AlinsRan requested a review from Copilot May 14, 2026 05:52

Copilot started reviewing on behalf of AlinsRan May 14, 2026 05:52 View session

Copilot AI reviewed May 14, 2026

View reviewed changes

dosubot Bot added size:XL This PR changes 500-999 lines, ignoring generated files. and removed size:XXL This PR changes 1000+ lines, ignoring generated files. labels May 14, 2026

AlinsRan and others added 8 commits May 14, 2026 14:15

fix: fix typo unparseable -> unparsable in test description

3019135

fix: fix luacheck warning - avoid overwriting err variable

ef7e21d

refactor: rename max_query_depth to node_depth

ce2f301

fix(tests): reindex test cases after merging TEST 2+3

34fafe7

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

nic-6443 previously approved these changes May 21, 2026

View reviewed changes

membphis previously approved these changes May 22, 2026

View reviewed changes

AlinsRan dismissed stale reviews from membphis and nic-6443 via 637fe1c May 22, 2026 07:38

dosubot Bot added size:XXL This PR changes 1000+ lines, ignoring generated files. and removed size:XL This PR changes 500-999 lines, ignoring generated files. labels May 22, 2026

AlinsRan and others added 12 commits May 22, 2026 15:55

fix(graphql-limit-count): localize ipairs to satisfy lj-releng

9cfb56b

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

fix(graphql-limit-count): localize tonumber to satisfy lj-releng lint

464c0c7

lj-releng reports an error for Lua globals accessed without local bindings. Add local tonumber = tonumber with the other local aliases. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

fix(graphql-limit-count): remove request body from error log messages

f7f3f38

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(plugin): add graphql-limit-count plugin#13372

feat(plugin): add graphql-limit-count plugin#13372
AlinsRan wants to merge 24 commits into
masterfrom
feat/graphql-limit-count

AlinsRan commented May 14, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

membphis commented May 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

AlinsRan commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Why is this change needed?

How does it work?

Example

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

membphis commented May 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AlinsRan commented May 14, 2026 •

edited

Loading